home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Suzy B Software 2
/
Suzy B Software CD-ROM 2 (1994).iso
/
new_file
/
extras
/
atarivew
/
docs
/
techman.doc
< prev
Wrap
Text File
|
1991-05-26
|
30KB
|
834 lines
063010303010000126002006006002000
1 AtariView V1.03 1
2 Page # 1
F0110030001
9[.............................................................]1010
Ç AtariView 1.10
Atari-ST
Written by Tony Hoyle
* This is the technical manual. For user information see ATARIVIEW.DOC *
9[...............................................................................................]2010
Ç êModule Headers
Ç
Each module is a standard relocatable file with the following in the first few
bytes of the program:
$0 DC.W $ABCD VTOS Module identification.
$2 DC.L Setup Program initialisation address or 0.
$6 DC.L Menu Address of Menu option associated with this module.
$A DC.L Next Module chain - can be used to put more than one module
into a file (Zero if no more).
The Module ID must be a constant as GEM will not relocate a program which has
a relocatable value in its first word.
Modules are entered in user mode, although there is no restriction placed upon
using supervisor mode.
The basepage for each module is not created, and modules must not attempt to
re-allocate space to GEM. Space may be allocated by creating memory blocks if
needed.
êMenu Structure
Ç
The 'Draw Menu' routine is called with the address of a list of longwords.
Each longword points to a Menu string, as detailed below. In addition, the
first word of the list is the number of Menu options, and the next Longword is
the address of the Title string (which is just the string terminated by a
null).
Each Menu entry contains 3 portions - A status byte, An Address, and the menu
string. This is in the following format:
DC.B status,'Menu Text'
DC.L address
The first byte of the address (always 0) is taken as the End of the string,
therefore the menu text must always be an odd number of bytes long otherwise a
bus error will result.
The status byte is bit significant, as follows:
Bit 0 Set if the option is selectable (ie. Enabled).
Bit 1 Set if clicking on this opion causes execution, reset if it causes
another menu to be displayed.
The address either points to the next menu parameter table, or the execution
address of the option, depending on the status of bit 1.
êInput Routine
Ç
This is called just before the keyboard is scanned during 'Get String'. It is
intended to be used by the calling routine to monitor mouse interaction (An
example of its use is in the file selector).
Input: A0 = Pointer to next character in input string.
Ç D1 = Current length of input string.
D2 = Maximum length of input string.
D3 = Last character code entered.
Output: D0 = 0, No special action needed.
1, Abandon the input as if Right Mouse pressed.
2, Terminate as if Return pressed.
3, Redisplay the input string and restart input.
êTop Line Array Structure
Ç
The top-line address passed to function 28 points to an array of fairly simple
data, but this must be defined correctly or a crash me result.
The Array is defined as follows:
TopLine.40 40 character line of ASCII.
Number.b A byte defining the number of PDMs on this top line.
Unused.b This byte must be zero.
Pointers.l Longwords pointing to each of the PDMs in order.
Each PDM (Pull Down Menu) is defined as follows:
Offset.w The offset in characters from the left edge of the screen of
this PDM.
OptionEnd.w Character position of the right edge of the PDM option.
Depth.w The depth of the PDM in lines (also the number of options).
Width.w The width of the PDM in characters.
Options Each option string in order, terminated by a null and prefixed
by a byte which defines whether the option is active or not
(1=Off, 2=On).
êResponse frame Control arrays
Ç
These arrays define the action of the Response Frame handler upon the frame
passed to it. You can define flexibly any number of fields and mouse buttons
according to requirements.
The Array is a null terminated list of entries which may be of one of two
types. Details of each type are as follows:
Field Entry:
DC.B 'F',fieldtype
DC.W Xposition * X position of field
DC.W Yposition * Y position of field
DC.W Length * Length of field
DC.L CharList * Character list for type 2 fields.
Mouse Entry:
DC.B 'M',mousetype
DC.W Xposition * X position of button
DC.W Yposition * Y position of button
DC.W Length * Length of button text
Ç DC.L Routine * Routine address for type 2 buttons.
Error Entry:
DC.B 'E',0
DC.W Xposition * X position of control code (see below)
DC.W Yposition * Y position of control code (see below)
DC.W 0 * Reserved - Specify as zero
DC.L 0 * Reserved - Specify as zero
'fieldtype' = 0 means any character may be put into the field.
= 1 means only digits may be put into the field
= 2 means only characters defined in the character list may be put
into the field.
+$40 means the field must not be empty.
+$80 meand the field must be full.
'mousetype' = 0 means this is an OK Button.
= 1 means this is a Cancel Button.
= 2 means 'Routine' is called every time this button is clicked.
êError EntriesÇ
Each error entry points to one square, which will be initialised to 1 (Red
ink) or 0 (Black ink) before the frame is displayed, depending on the relevent
bit of d7 supplied when 'DoResponse' is called.
êDefining Memory Blocks
Ç
All memory blocks have a standard format header as follows:
$00 DC.L Length Length of data +24 for header.
$04 DS.B 16 Name of block
$14 DC.W Type Type of block (bit significant).
Frames are of type $0001 ($0003 if they include routes). Templates are of
type $0100, and most system blocks are of type $8000 (The phone and mailbox
directories are stored as blocks).
A frame is defined as follows:
$16 DC.W Pages Number of pages stored
$18.... (For each page)
DS.B 960 The frame.
(Also if the frame contains routes)
DS.B 9 Page number.
DS.B 1 Frame ID.
DS.B 1 User Access (Y or N).
DS.B 5 CUG Number.
DS.B 8 Unused (Product number on Prestel - not uploaded).
Ç DS.B 6 Price in 10ths/p.
DS.B 9*10 Choices for keys 0..9.
DS.B 1 Frame Type.
DS.B 1 Update Option.
All entries are in the same format as required for Prestel Bulk Update.
9[..................................................................]1010
Ç êVTOS system variables (Base passed in A1 on initialisation)
Ç
Offset Name Purpose
0000 Xposition.w Cursor X position
0002 Yposition.w Cursor Y position
0004 ScreenBuffer.l Base of viewdata screen
0008 MouseFlags.b Mouse Flags register (see below)
0009 CurFlags.b Cursor and reveal flags (see below)
000A Flags.b Character state flags (see below)
000B Colours.b Background/Foreground colours
000C LastGraph.b Last graphic character displayed
000D Speed.b RS232 Transmit speed
000E RSBits.b Number of bits (7 or 8)
000F RSParity.b Parity (0=None, 1=Odd, 2=Even)
0010 RSStop.b Number of stop bits
0011 RSFlags.b RS232 status flags (see below)
0012 MouseX.w Mouse X position
0014 MouseY.w Mouse Y position
0016 BaseOfFree.l Base of memory
001A TopOfFree.l Top of memory
001E CurrentBase.l Current base of free memory
0022 MouseVector.l Routine called on mouse button event
0026 Button.b Mouse button status
0027 SysFlags.b System flags - not user alterable
0028 ScreenBase.l Base of displayed screen
002C CursorAddr.l Address of cursor character
0030 CursorAddr2.l Cursor for shadow screen
0034 ShadowScreenP.l Base of shadow screen
0038 Char.w RS232 75 baud character (10/11 bit)
003A Timer.w RS232 75 baud timer
003C GraphBuff.l 4 byte graphic character buffer
0040 CursorStore.8 8 byte cursor background store
0048 CursorStore2.8 Store for shadow screen
0050 Unused.8 Unused 8 byte buffer
0058 DoubleList.24 24 line Double Height counter
0070 FlashList.8 8 byte flashing colour list
0078 NextFlash.b Next flash character to be used
0079 FlashLength.b Current length of flash list
ł007A ModuleCount.b Number of modules in the system
007B FlashOnRate.b Flash on period
007C FlashOffRate.b Flash off period
007D CursorRate.b Cursor flash rate
007E CursorCount.b Cursor flash rate counter
007F FlashCount.b Flash rate counter
0080 LastInk.b Temporary ink colour store
0081 BuffLen.b Length of 75 baud Tx Character
0082 CharVec.l Background mode character handler
0086 CallTimer.w Seconds per chargeable unit (*100)
008A UnitPrice.l Price per unit in 100ths/p
008E CurrentPrice.l Price of current call in 100ths/p
0092 SecondCount.b Vblanks until next second
0093 ScreenFlags.b Flags controlling screen mode (see below)
0094 Identity.l Pointer to login string (cleared after use)
0098 InpVector.l Address of routine called during 'Get String'
009C KMacro.l Address of keyboard macro string
00A0 Year.B BCD Year at last enquiry
00A1 Month.B BCD Month at last enquiry
00A2 Day.B BCD Day at last enquiry
00A3 Hour.B BCD Hour at last enquiry
00A4 Minute.B BCD Minute at last enquiry
00A5 Second.B BCD Second at last enquiry (in steps of 2)
00A6 Today.B Day of week (0=Saturday,2=Monday,6=Friday)
ê'Flags' - Character flag register
Ç
Bit Purpose
0 Set when ESC(27) has been sent. Reset automatically.
1 Set when Graphics mode is on.
2 Set when Hold Graphics is on.
3 Set when Conceal mode is on.
4 Set when Double Height is on.
5 Set when Flash mode is on.
6 Set when Separated graphics is on.
7 Temporary graphics flag (always zero).
ê'CurFlags' - Cursor flag register
Ç
Bit Purpose
0 Set if the cursor is enabled.
1 Set when the screen is Revealed.
2 Set when the cursor is actually on the screen.
3 Interrupt lock register - set before writing to the screen.
4 Cursor flashing register - used by interrupt.
5 Character flashing register - used by interrupt.
6 Set if the inks need updating.
≤Ç ê'MouseFlags' - Mouse flag register
Ç
Bit Purpose
0 Set if the mouse is enabled.
1 Reset if the mouse is on the screen.
2 Set to draw the mouse next Vblank.
3 Set if Multiflash is enabled.
4 If reset incoming characters are dealt with in the background.
5 If set this screen may be revealed (eg. Buffer is valid).
6 Not used.
7 If set bottom line will be redisplayed next Vblank.
ê'RSFlags' - RS232 status register
Ç
Bit Purpose
0 DCD (Data carrier detect)
1 CTS (Clear to send)
ê'ScreenFlags' - Screen control flags
Ç
Bit Purpose
0 If set the screen is displayed in black and white.
1 If set the screen scrolls instead of wrapping to the top.
2 Set when the mouse is clicked on the top line.
3 Set to ignore any Double Height characters (used for PDMs).
Ç êCalling Conventions
Ç
VTOS is accessed through a table of address, the base of which is passed in
register A0 when a module is initialised. Register A1 points to the VTOS
system variables.
The GEM VDI and AES calls cannot be used when VTOS is resident. In addition,
the GEM mouse is not used so mouse related A-Line calls will not work.
êVTOS Calls
Ç
ü0:High-Level character display (Offset 0).Ç
Input: D0.B = Character to display on the screen.
Output: None.
All Control codes are filtered, Escape codes are expanded and the screen
buffer is updated. Colour codes cause the screen to be refreshed. All
registers are preserved by this call.
ü1:Low-Level character display (Offset 4).Ç
Input: D0.B = Character to display in the screen.
Output: None.
Characters 0..31 are treated as escape codes. The character is not put into
the screen buffer.
ü2:Recieve character from RS232 (Offset 8).Ç
Input: None.
Output: D0.W set to recieved character, or -1 if none.
This routine must be used rather than the GEMDOS routine.
ü3:Send character to RS232 (Offset 12).Ç
Input: D0.B = Character to send.
Output: None.
Use instead of the GEMDOS routine. This routine handles 1200/75 baud
correctly, but ignores the state of RTS or CTS.
±ü4:Configure RS232 (Offset 16).Ç
Input: RSBits, RSParity, RSStop, Speed set to correct values.
Speed values are: 0=110 baud,
1=600 baud,
2=1200 baud,
3=2400 baud,
4=4800 baud,
5=9600 baud,
6=1200/75 baud,
7=300 baud.
Output: None.
Use instead of the GEMDOS setup routine.
ü5:Store the online screen and enter background mode (Offset 20).Ç
Input: None.
Output: None.
The online screen is stored in a special buffer and any new incoming
characters from the RS232 are dealt with in the background.
ü6:Re-display the online screen and enter foreground mode (Offset 24).Ç
Input: None.
Output: None.
After this call it is the program's responsibility to deal with any incoming
characters. The screen is restored completely to the state it was in before
it was last stored.
ü7:Erase cursor (Offset 28).Ç
Input: None.
Output: None.
Ensures that the cursor has been removed from the screen. Call this routine
after resetting the 'Cursor Enable' bit in the cursor flags.
Ensure that the 'Lock' bit in the cursor flags is set before calling this
routine.
÷ü8:Display Cursor (Offset 32).Ç
Input: None.
Output: None.
Places the cursor on the screen immediately.
Ensure that the 'Lock' bit in the cursor flags is set before calling this
routine.
ü9:Move cursor (Offset 36).Ç
Input: None.
Output: None.
Erases the cursor from its current position, and places it at the position
defined by the cursor X and Y position in the system variables.
This routine should not normally be needed, but if it is used, ensure that the
'Lock' bit in the cursor flags is set.
ü10:Point to next character cell (Offset 40).Ç
Input: None.
Output: None.
Performs a cursor right, wrapping if necessary but not updating the cursor.
ü11:Store character in current position (Offset 44).Ç
Input: D0.B = Character to store.
Output: None.
Stores a character in the current cell, and updates the Double Height list if
necessary.
ü12:Act upon a control code (Offset 48).Ç
Input: D0.B = Control code.
Output: None.
The cursor may need updating after this routine.
ü13:Find out what colour the current character is (Offset 52).
Ç
Input: None.
Output: None.
Updates the colours and flags to be relevant to the current cell.
Use after altering the cursor position.
÷ü14:Enable the mouse (Offset 56).Ç
Input: D0.B = 0, Place on the screen next Vblank,
= 1, Place on the screen when it is next moved.
Output: None.
Use instead of the A-Line routine. If a Disable Mouse call is encountered
before the next Vblank, the mouse will not appear.
ü15:Disable the mouse (Offset 60).Ç
Input: None.
Output: None.
Use instead of the A-Line routine. This removes the mouse from the screen
immediately, and stops it from being redrawn.
ü16:Load and relocate a module (Offset 64).
Ç
Input: A0.L = Address of filename (null terminated).
A6.L = Where to place the file.
Output: A6.L = The end of the file.
A5.L = The old value of A6 (beginning of the file).
Use instead of the GEM rouine. This does not create a basepage, and modules
may be placed anywhere in memory. A6 is NOT range-checked.
ü17:Get a key from the keyboard (Offset 68).Ç
Input: None.
Output: D0.W = Key pressed. If D0.W=0 then no key was pressed.
High word of D0 is shift-key status as returned by BIOS 11.
This routine translates keys such as Enter, £ and # to return the equivalent
viewdata code.
ü18:Get a string from the keyboard (Offset 72).Ç
Input: A0.L = Address of buffer.
D2.W = Maximum length of buffer.
Output: Buffer filled with input string, D1.W = Length of string.
D0=0, OK. D0=1, Right mouse button pressed.
D3=Key which caused return.
The cursor woll be disabled after calling this routine. During execution the
cursor is enabled. The buffer should be initialised before calling to either
nulls or spaces (the routine will return a string in the same format as it is
sent - Space filled or Null terminated). If the buffer contains characters
these will be displayed and the cursor positioned after the last non-space.
≈ü19:Allocate a memory block (Offset 76).Ç
Input: A0.L = Address of standard format block to put into the system.
Output: If D0.W=0 then the block was allocated properly - A1 points to it.
If D0.W=1 then a block with that name and ID already exists - A0
points to it.
If D0.W=2 then there was not enough memory.
ü20:Remove a memory block (Offset 80).Ç
Input: A0.L = Address of standard format block header.
Output: If D0.W=0 then the block was removed successfully.
If D0.W=1 then the block did not exist.
ü21:Find a memory block (Offset 84).Ç
Input: A0.L = Address of standard format block header.
Output: A0.L = Address of block if found.
If D0.W=0 then the block was found.
If D0.W=1 then the block did not exist.
Use this to search for indefinite files. To facilitate this the block name
may contain the wildcards '?' and '*', and if the block type is set to $FFFF
then any block with that name will be found.
ü22:Find the next memory block (Offset 88).Ç
Input: D1 and A0/A1 from 'Find Block'.
Output: As for 'Find Block'.
ü23:Refresh the current screen (Offset 92).Ç
Input: D0.B=0, don't clear the screen first.
<>0, clear the screen first.
A0.L=Address of buffer.
Output: None.
Use this to refresh the screen after it has become corrupted (perhaps by the
file selector).
ü24:Clear the status line and point to it (Offset 96).Ç
Input: None.
Output: None.
This function is intended for use by programs which display errors or request
input. It does not store the colours and should be used with care.
εü25:Display file selector and fetch a filename (Offset 100).Ç
Input: A0.L = Address of filename buffer.
A1.L = Address of heading string.
A2.L = File to search for (block if searching RAM).
A3.L = Default path (Disk only).
D0.W = Length of filename.
D1.B = 0,RAM or 1,Disk.
Output: A0.L = Filename padded with spaces.
A1.L = Full pathname of file (zero terminated).
D0.W = 0, OK.
<> 0, Error.
This function should be used instead of the GEM file selector. It is
recommended that the full pathname returned is used for disk files (this is
not initialised for RAM files).
ü26:Dial a number (Offser 104).Ç
Input: A0.L = Telephone number (zero terminated).
A1.L = Dial command string.
D0.B = Dial type: 0 - None.
1 - RTS and DTR.
2 - Smart, using dial command.
Output: None.
This function causes the Modem to pick up the line and dial. If D0=0 then the
routine just returns. The number is an ASCII string, which may contain commas
and spaces. '^' is used to denote control codes in the dial command - '^M' is
Return.
ü27:Use predefined colour macro (Offset 108).Ç
Input: D0.W = Function key number (1..10).
D1.W = Shift key status - bit 0 = Shift.
1 = Ctrl.
2 = Alt.
Output: None.
This function is used to implement the predefined colour macros. The shift
key and function key values may be derived from the values returned from
Function 17 (Get Key).
⌠ü28:Monitor interaction with the top line (Offset 116).Ç
Input: A0.L = Top line Array address.
Output: D0.W = PDM number selected (0..n).
D1.W = Option number within PDM (0..n).
Use this function to implement pull-down menus. If during the execution of a
program it finds bit 2 of ScreenFlags is set this routine should be called,
and the bit reset. If D0.W is negative then nothing was selected, and D1 is
meaningless.
ü29:Raise DTR and RTS (Offset 120).Ç
Input: None.
Output: None.
This is used to tell a Modem that you are about to go online, and with some
Modems it will actually pick up the line. Use before dialling.
ü30:Drop DTR and RTS if no DCDÇ ü(Offset 124).Ç
Input: None.
Output: None.
Use this routine on exit from a terminal emulator. If there is no carrier the
line will be dropped.
#ü31:Enter Response Frame handler (Offset 128).Ç
Input: A0.L = Address of blank Response Frame.
A1.L = Address of Control Array.
A2.L = Address of auto-exec routine or 0.
A3.L = Default fields.
D7.B = Bit significant error handler flags
Output: D0.W = 0, OK.
<>0, Cancel.
D3.W = Mouse button that caused exit (1..n).
If a 'Cancel' button is pressed to exit the Default Fields are preserved,
otherwise they are changed to reflect what the user entered. The value in D3
may be used to implement special routines such as 'Next Frame' buttons.
The error handler flags are tested when an 'E' field is found. The first 'E'
field is bit 0, the second is bit 1, etc. You may only have 8 'E' fields in
any one frame.
∩ü32:Field Conversion (Offset 132).Ç
Input: D1.W = Length of field.
D0.B = Conversion type:
0: Convert ASCII number in (A0) to (A1) adding leading zeros.
1: Convert ASCII number in (A0) to (A1) removing leading zeros.
2: Convert ASCII number in (A0) to D0.L.
3: Copy (A0) to (A1) removing trailing null.
4: Copy (A0) to (A1) adding null at end of string.
5: Convert Longword at (A0) to ASCII at (A1).
Output: See above.
This is useful for converting output from response frames (which is always
space filled ASCII) to internal representations of the data.
ü33:Refresh Time & Date values (Offset 136).Ç
Input: None.
Output: None.
Call this routine before reading BCD Time & Date from system variables.
Ç**************************************************************************
* SYSRESET.S *
* *
* Written using Hisoft Devpac-2 *
* *
* Example VDT file, which adds the option to reset the system *
* This program is rather verbose in places...! *
* *
* Version 1.00 11th September 1989 *
* Added new VTOS calls - Version 1.01 27th May 1990 *
* *
**************************************************************************
opt o+ * Optimisation on
output .VDT * Override default .PRG
section text
* The CallVTOS macro is quite handy. Feel free to use it in your own
* programs.
CallVTOS: macro
clr.l -(sp) * Dummy argument
move.l a0,-(sp) * Store register
move.l VtosBase,a0 * Base of table
move.l \1*4(a0),4(sp) * Store jump
move.l (sp)+,a0 * Retrieve register
rts * Indirect jump to routine
endm
* This is where the program code starts. First we must define the
* VTOS header.
dc.w $abcd * This is a VTOS module
dc.l Setup * Initialisation
dc.l ResetMenu * Menu option
dc.l 0 * No chain
* Note the above value may be altered. To put more than one module in
* a single file use the 'chain' value to define where the next header
* is.
* Initialisation - Must not alter registers a0-a5 or d0-d7
Setup: movem.l a0-a5/d0-d7,-(sp)
move.l a0,VtosBase * VTOS base address
move.l a1,VtosBss * VTOS BSS address
move.l a1,a6 * Set base pointer
* Put your initialisation here!
* A6 is not altered by any VTOS routines, and by convention points to the
* VTOS BSS address. Alter this at your peril!
movem.l (sp)+,a0-a5/d0-d7
rts
Ç
Reset: move.b $26(a6),d0 * Fetch mouse button status
and.b #$fc,d0 * Wait for mouse to be stopped
bne Reset * Wait for it...!
* The next bit is a pretty standard system-reset routine
* The purpose of waiting for both mouse buttons to be lifted is because
* the IKBD controller gets confused if you hold down a mouse button during
* a system reset.
clr.l -(sp) * SSP=USP
move.w #$20,-(sp) * Supervisor/User mode toggle
trap #1
move.l $4f2,a0 * System reset PC address
move.l (a0),-(sp) * Fetch reset value
rts * Jump into it!
* Although not used by this program, VTOS calls are defined as follows.
* See VTOS technical manual for further details on each routine
PrintCharacter: CallVTOS 0
DisplayChar: CallVTOS 1
RxCharacter: CallVTOS 2
TxCharacter: CallVTOS 3
ConfigRS232: CallVTOS 4
GotoBackground: CallVTOS 5
GotoOnline: CallVTOS 6
EraseCursor: CallVTOS 7
DisplayCursor: CallVTOS 8
MoveCursor: CallVTOS 9
StepToNext: CallVTOS 10
StoreCharacter: CallVTOS 11
ControlAction: CallVTOS 12
GetColour: CallVTOS 13
MouseOn: CallVTOS 14
MouseOff: CallVTOS 15
LoadRelocate: CallVTOS 16
GetKey: CallVTOS 17
GetString: CallVTOS 18
AllocateBlock: CallVTOS 19
RemoveBlock: CallVTOS 20
FindBlock: CallVTOS 21
FindNext: CallVTOS 22
RfshScreen: CallVTOS 23
ClearBottom: CallVTOS 24
FileSelector: CallVTOS 25
DialComputer: CallVTOS 26
UseColour: CallVTOS 27
UseTopLine: CallVTOS 28
RaiseDTR: CallVTOS 29
DropDTR: CallVTOS 30
DoResponse: CallVTOS 31
ConvertField: CallVTOS 32
FetchTime: CallVTOS 33
RapidDisplay: CallVTOS 34
ÇReadCookie: CallVTOS 35
WriteCookie: CallVTOS 36
section data
* The menus are defined here
ResetMenu: dc.b 1,'Reset System ' * Enabled, goes to menu
dc.l ResetSubMenu * Address of menu
ResetSubMenu: dc.w 1 * Just one option
dc.l ResetSubTitle * Title string
dc.l ResetSubOpt1 * Option 1
ResetSubTitle: dc.b 'Reset system',0 * Title string
even
* Note the line below is the same format as 'ResetMenu'
* Remember each option string must be of an odd length.
ResetSubOpt1: dc.b 3,'Yes Please ' * Enabled, executes
dc.l Reset * Routine address
section bss
VtosBase: ds.l 1 * VTOS jump-table address
VtosBss: ds.l 1 * VTOS system variables
Ç
